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A  Command  Editor  Tool  for 
NEXTSTEP 


MARBLE  ASSOCIATES,  INC. 


The  final  report  prepared  for  DARPA  under  Contract  # 
DAAH01  -93-C-RO 1 3. 


Final  Report 


1.0  Executive  Summary 

Marble  Associates,  Inc.,  is  engaged  in  the  development  of  customizable  menus  in 
NEXTSTEP  and  the  design  of  customizable  menus  in  the  X  windowing  environment. 
In  this  document,  we  present  the  final  design  and  implementation  details  of  the  Com¬ 
mand  Editor  in  NEXTSTEP.  To  reiterate  the  objectives  stated  in  previous  submissions, 
we  strive  to  do  the  following  in  building  the  Command  Editor : 

•  retain  all  functionalities  of  the  standard  NEXTSTEP  environment ; 

•  add  functionalities  in  a  manner  keeping  with  NEXTSTEP,  mimicking  the  user 
and  developer  interaction  mechanisms  of  NEXTSTEP;  and 

•  maintain  interoperability  among  our  customized  objects  and  standard  system 
objects. 

Our  realization  of  the  Command  Editor  for  NEXTSTEP  adheres  closely  to  the  original 
design  presented  in  Progress  Report  #1.  As  suggested  in  that  report,  newly  discovered 
challenges  necessitate  slight  departures  from  the  design.  Our  objective  is  to  provide  to 
the  user  and  the  developer  the  functionality  outlined  in  the  Phase  I  Proposal  and  the 
Progress  Report  #1.  This  document  discusses  in  detail  the  challenges  we  faced,  our  so¬ 
lutions,  and  the  subsequent  impact  on  the  design  and  functionality  of  the  Command  Ed¬ 
itor.  We  also  address  some  adjustments  to  our  original  targeted  functionalities  forced 
by  the  NEXTSTEP  environment. 

Though  a  complete  discussion  is  presented,  this  document  assumes  that  the  reader  is  fa¬ 
miliar  with  concepts  and  terminology  presented  in  previous  papers  submitted  under 
•  7  s-r*y  9  Contract  #  DAAH01-93-C-R013.  For  a  listing  of  previous  submissions,  please  refer  to 

DTIC  Appendix  B. 
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2.0  Background 


This  section  introduces  terms  and  concepts  necessary  for  subsequent  discussions.  We 
present  a  synopsis  of  user  and  developer  functionalities  to  recap  the  concepts  described 
in  previous  submissions.  For  a  complete  functional  specification,  please  refer  to  The 
Command  Editor:  A  Manual  for  Users  and  Developers. 

2.1  Menu  Types 

We  have  separated  the  menu  systems  deployed  in  the  Command  Editor  into  three 
states.  Each  state  represents  a  distinct  stage  in  ihe  life  cycle  of  the  application  menu, 
from  its  construction  in  Interface  Builder  OB),  through  its  initial  instantiation  at  runt¬ 
ime,  to  its  modification  by  the  end  user  (Figure  1). 

•  The  FullMenu  is  the  menu  structure  composed  by  the  developer  to  contain 
the  complete  set  of  commands  available  for  end  user  customization. 

:  the  BasicMenu  is  also  determined  by  the  developer  and  represents  the  initial 

menu  configuration  visible  at  runtime  prior  to  any  user  customization.  The 
BasicMenu  is  a  subset  of  the  FullMenu.  The  developer  composes  this  menu 
in  IB  by  marking  members  of  the  FullMenu  as  “Default.” 

*  The  CustomizedMenu  is  the  end  user  modified  menu.  This  menu  is  a  modi¬ 
fied  BasicMenu  and  can  contain  CEMenuCells  from  the  FullMenu  not 
marked  “Default”  by  the  developer. 

We  note  that  the  BasicMenu  and  CustomizedMenu  are  not  separate  objects;  rather, 
the  visible  menu  is  in  one  of  these  states.  When  the  application  displays  the  initial 
menu  configuration  dictated  by  the  developer,  we  call  the  menu  structure  the  Basic- 
Menu.  When  the  user  alters  the  application  menu,  we  call  the  menu  structure  the  Cus¬ 
tomizedMenu.  The  distinction  is  important  when  we  discuss  the  developer’s 
interactions  with  the  Command  Editor  in  IB  and  again  when  we  describe  the  CECon- 
troller  actions  on  startup.  Indeed,  we  will  refer  to  the  application  menu  as  the  “visible 
menu”  regardless  of  its  configuration  (BasicMenu  or  CustomizedMenu)  only  when 
the  distinction  is  irrelevant. 

The  “invisible”  menu,  then,  is  the  FullMenu.  This  structure  represents  the  topology  of 
available  commands  configured  by  the  developer.  It  is  “invisible”  in  the  sense  that  the 
end  user  never  directly  interacts  with  this  structure  as  a  menu.  The  user  can  browse 
through  this  topology  using  the  Menu  Editor,  however.  The  FullMenu  is  stored  in  the 
application  NIB  at  the  completion  of  developer  configuration  in  IB.  Within  the  Full- 
Menu,  certain  CEMenuCells  are  marked  “Default”  by  the  developer  via  the  CEMenu- 
Celllnspector. 

At  runtime,  the  application  will  search  the  user’s  home  directory  for  a  profile  (.applica- 
tionName.ee info).  If  this  file  is  available,  the  CEController  loads  the  customization  in 
this  file.  The  load  process  instantiates  the  archived  menu  structure.  The  CEController 
then  makes  this  newly  instantiated,  customized  menu  the  application  menu.  If  the  cus¬ 
tomization  file  is  not  available,  the  CEController  constructs  the  BasicMenu  by  filter¬ 
ing  the  FullMenu. 

When  the  end  user  chooses  the  "Configure  Menus”  option  in  the  “Menu  Configura¬ 
tion”  submenu,  the  Menu  Editor  appears  and  presents  the  hierarchy  of  CEMenuCells 
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in  the  FullMenu.  The  user  can  then  browse  and  select  particular  menu  items  to  be  add¬ 
ed  via  drag  and  drop  (DND). 


FIGURE  1 


Menu  Types 
CEBasicMenu 


CECustomizedMenu 


CEFullMenu 


2.2  Developer  Functionality 

The  developer  builds  a  customizable  menu  for  his  application  by  loading  the  Com¬ 
mand  Editor  palette  in  IB  and  dragging  our  objects  from  this  palette  into  the  applica¬ 
tion  NIB  and  menu  structure  (Figure  2).  He  is  responsible  for  composing  the 
FullMenu  and  BasicMenu.  Additionally,  the  developer  can  incoiporate  TAVs  (Tool 
Acceptor  Views)  into  his  application  by  dragging  the  TAV  object  from  the  palette  and 
dropping  it  in  any  window  in  the  application  NIB.  TAVs  allow  the  end-user  to  load  of- 
ten-used  menu  commands  into  readily  accessible  buttons. 

The  developer  composes  the  FullMenu  by  dragging  CEMenuCells  or  CESubmenu- 
Cells  from  our  palette  onto  the  application  menu.  This  adds  new  menu  items  to  the 
FullMenu  hierarchy.  The  developer  configures  individual  items  (CEMenuCells  and 
CESubmenuCells)  using  the  appropriate  IB  Inspectors  provided  by  our  palette. 

The  developer  specifies  all  of  the  following  for  each  CEMenuCell  through  the  CEMe- 
nuCelllnspector:  action,  icon,  “Default”  status,  state  list,  textual  description,  tool  sta- 
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tus,  and  disable  status.  A  visual  indicator  will  distinguish  “Default”  items;  a  small 
square  notch  denotes  the  exclusion  of  that  item  from  the  BasicMenu. 

CESubmenuCells  allow  the  developer  to  add  and  populate  menu  curtains.  Though  we 
implement  the  CESubmenuCells  as  a  special  case  of  CEMenuCell,  we  will  continue 
using  the  term  CESubmenuCell  for  the  sake  of  clarity.  CESubmenuCells  require  the 
developer  to  specify  the  “Default”  and  “Disable”  status  via  the  CEMenuCelllnspec- 
tor.  We  defer  the  discussion  of  CESubmenuCell  implementation  to  Section  4.1.4.  The 
developer  can  also  specify  the  border  used  in  drawing  a  particular  TAV  via  the  CE- 
TAVInspector. 


FIGURE  2 
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The  CEMenuConfigCell  represents  the  “Menu  Configuration”  submenu  that  allows 
the  user  to  customize  the  application  menu.  Its  submenu  item-  include  “Configure 
Menus,”  “Save  Configuration,”  “Load  Configuration,”  and  “Show/Hide  Configurable 
Cells.”  Thus,  its  addition  to  the  menu  structure  is  required  if  the  end-user  is  to  browse 
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the  set  of  available  commands,  customize  TAVs,  or  load  and  save  configurations.  With¬ 
out  the  CEMenuConfigCell,  the  end-user  can  still  Control-drag  configurable  cells  to 
reorder  or  delete  menu  items.  The  developer  simply  drags  the  CEMenuConfigCell 
from  the  palette  and  drops  it  onto  the  application  menu.  Only  one  CEMenuConfig¬ 
Cell  should  be  added  to  an  application  menu.  If  more  than  one  is  added,  all  but  the  first 
instance  in  the  menu  structure  are  ignored 

The  developer  can  incorporate  standard,  non-customizable  MenuCells  into  the  applica¬ 
tion  menu.  While  these  menu  items  cannot  be  customized  or  deleted  by  the  end  user, 
their  position  in  the  menu  structure  can  be  altered  with  the  addition  and  deletion  of  cus¬ 
tomizable  menu  items. 

2.3  User  Functionality 

The  goal  of  Marble’s  Command  Editor  is  to  provide  the  functionalities  described  be¬ 
low.  The  user  can  customize  various  menu  characteristics  within  limits  dictated  by  the 
developer.  Through  the  “Configure”  submenu,  the  end  user  can  view  the  set  of  config¬ 
urable  items  in  the  menu  structure,  save  or  load  configurations,  and  customize  the 
menu  through  the  Menu  Editor  (Figure  3). 

When  requested  at  runtime,  the  Command  Editor  classes  bear  a  visual  indicator — a 
small  square  notch  left  adjusted  in  the  menu  item.  These  items  can  be  deleted  and  reor¬ 
dered  by  Control-dragging  them  off  the  menu  structure. 

The  Menu  Editor  allows  the  user  to  browse  the  FullMenu  and  select  a  customizable 
item  to  be  added  to  the  application  menu  or  TAV.  The  user  can  Control-drag  a  CEMe- 
nuCeli  or  CESubmenuCel!  from  the  browser  and  drop  it  into  the  desired  position  in 
any  menu  curtain  (Figure  4).  Dropping  the  CEMenuCell  onto  a  TAV  forces  the  TAV 
to  display  the  icon  associated  with  that  CEMenuCell.  Note  that  CESubmenuCells 
cannot  be  dragged  onto  TAVs. 

The  end  user  can  add  submenus  by  Control-dragging  the  button  from  the  “Additional 
Submenu”  portion  of  the  Menu  Editor  onto  the  application  menu  (Figure  5).  The  title 
of  this  submenu  can  be  entered  in  the  text  field  immediately  below  the  button.  The  sub¬ 
menu  curtain  added  will  contain  an  unconfigured  item  initially  (Figure  6).  The  user 
can  then  configure  this  new  menu  curtain  via  DND. 

CKEs  allow  the  user  to  type  Command-Key  to  activate  a  menu  selection  without  using 
the  mouse.  To  specify  the  CKE  of  any  configurable  menu  item,  the  user  enters  the  new 
character  in  the  “Command  Key  Equivalent”  field  of  the  Menu  Editor.  The  CKE  will 
update  for  items  currently  displayed  in  the  application  menu. 

The  user  can  configure  a  TAV  by  dragging  a  command  from  the  Menu  Editor  (Figure 
7)  or  visible  menu  and  dropping  that  command  on  the  desired  TAV.  This  command 
must  have  its  hasTool  field  enabled,  indicating  a  valid  image  in  its  icon  field. 

As  a  final  note,  we  do  not  allow  the  user  to  add  menu  items  to  the  “Menu  Configura¬ 
tion”  submenu.  The  user  cannot  delete  items  from  this  menu  curtain  nor  can  he  specify 
CKEs.  Indeed,  the  Menu  Editor  displays  the  “Menu  Configuration”  item  in  “grayed 
out”  fashion,  precluding  user  interaction  with  this  item. 
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FIGURE  4 
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FIGURE  7 
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3.0  Architectural  Overview 


The  components  and  functionalities  of  the  Command  Editor  can  be  classified  into  two 
categories:  those  necessary  for  IB  and  paletting  and  those  necessary  at  runtime. 

3.1  IB  and  Paletting  Components 

Palette  objects  include  the  CEControIler,  CEMenuCell,  CESubmenuCell,  CEMenu- 
ConfigCell,  and  the  TAV.  Each  class  conforms  to  protocols  required  of  the  paletting 
mechanism,  associating  itself  with  the  correct  IB  Inspector. 

IB  Inspectors  allow  the  developer  to  configure  the  palette  objects.  Specifically,  the  CE- 
MenuCelllnspector  allows  specification  of  CEMenuCell  fields  discussed  in  Section 
2.2.  The  CEMenuCelllnspector  also  allows  the  specification  of  “Default”  and  “Dis¬ 
able”  status  for  CESubmenuCells,  which  are  implemented  as  CEMenuCells.  Similar¬ 
ly,  the  CETAVInspector  allows  the  specification  of  the  TAV’s  border. 

While  the  CEControIler  is  the  central  control  module  at  runtime,  its  duties  are  limited 
within  IB.  The  CEControIler  comes  into  play  when  IB  saves  the  developer’s  applica¬ 
tion,  at  which  time  it  composes  a  translation  table  to  be  used  at  runtime  and  archives 
this  table  to  the  resulting  NIB.  We  defer  the  full  discussion  of  this  table  to  Section  5.2. 
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The  FulIMenu  stores  the  hierarchical  structure  of  the  application  menu  and  the  infor¬ 
mation  relevant  to  each  menu  item.  The  reader  may  recall  that  our  original  design 
called  for  the  building  of  a  data  structure  by  the  CEController  that  represents  this  in¬ 
formation.  Based  upon  further  analysis,  we  have  removed  this  role  of  the  CEControl¬ 
ler;  we  extract  the  information  from  the  FulIMenu  at  runtime. 


3.2  Runtime  Components 

This  section  introduces  the  major  Command  Editor  components  present  in  the  applica¬ 
tion  at  runtime.  To  clarify  each  component’s  role,  we  provide  a  brief  description  of  the 
component’s  duties.  We  omit  certain  steps  for  brevity  and  defer  the  complete  discus¬ 
sion  to  Section  4.2. 

At  runtime,  the  application  NIB  is  unarchived  by  NEXTSTEP’S  Application  object. 
The  Command  Editor  objects  that  archived  themselves  as  part  of  the  app.ication  NIB 
are  reconstituted:  the  CEController  and  its  translation  table,  the  FulIMenu,  the  Menu 
Editor,  and  the  TA' s  dropped  onto  the  application  NIB.  The  CEController  is  respon¬ 
sible  for  initializing  all  Command  Editor  objects  and  constructing  the  application 
menu. 

The  CEController  initializes  the  FulIMenu  by  replacing  all  instances  of  Menu  and 
Matrix  in  that  structure  with  CEMenu  and  CEMenuMatrix,  which  contain  DND  log¬ 
ic.  Though  the  user  will  never  interact  with  FulIMenu  directly,  thus  requiring  DND  in 
that  structure,  this  replacement  facilitates  the  subsequent  task  of  building  the  applica¬ 
tion  menu.  Building  the  visible  menu  involves  copying  the  structure  of  the  FulIMenu, 
and  the  replacement  of  Menu  and  Matrix  with  CEMenu  and  CEMenuMatrix  saves 
the  CEController  from  performing  the  same  task  in  the  newly  construe  “*d  menu. 

On  startup,  the  application’s  menu  should  be  replaced  by  either  the  user’s  customized 
menu  or  the  BasicMenu.  In  the  absence  of  a  user  profile  (.applicaiionName. ceinfo), 
the  CEController  constructs  the  BasicMenu  by  replicating  a  subset  of  the  FulIMenu. 
This  replication  is  the  filtration  by  which  menu  items  not  marked  “Default”  are  re¬ 
moved  from  the  BasicMenu. 

In  the  presence  of  a  user  profile,  the  CEController  loads  the  visible  menu  directly 
from  the  file,  which  is  an  actual  archive  of  a  user  modified  menu.  Each  CEMenuCell 
then  uses  a  translation  table  maintained  by  the  CEController  to  assign  its  individual 
target  action.  This  concept  will  be  discussed  in  detail  in  Section  5.2. 

The  Menu  Editor  displays  the  FulIMenu  and  allows  the  user  to  customize  the  applica¬ 
tion  menu.  The  Menu  Editor  window  appears  when  the  user  selects  “Configure 
Menus”  from  the  “Menu  Configuration”  submenu. 

The  user  customizations  are  stored  in  the  visible  menu  itself.  The  user  can  save  this 
configuration  through  the  “Save  Configuration”  item.  The  menu  structure  simply  ar¬ 
chives  itself  to  disk,  writing  out  translation  table  information  in  the  process.  This  trans¬ 
lation  table  information  allows  the  CEMenuCells  to  reestablish  their  connection 
information. 

The  TAVs  are  unarchived  by  NEXTSTEP  at  runtime  as  views  in  the  application  NIB. 
Subclassed  to  handle  DND  directly,  the  TAVs  need  no  initialization  from  the  CECon- 
Iroller.  In  the  presence  of  a  user  profile,  however,  the  TAVs  require  the  CEController 
to  reestablish  connection  information.  Conversely,  when  the  user  saves  his  customiza- 
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tions,  the  CEController  archives  the  TAV  configuration  along  with  the  visible  menu 
archive. 


4.0  Implementation 


4.1  Implementation  of  Developer  Functionalities 

This  section  covers  the  implementation  of  classes  necessary  to  provide  the  developer’s 
suite  of  functionality  described  in  Section  2.2.  We  also  discuss  the  implementation  of 
components  that  assume  special  roles  in  IB  to  provide  certain  user  functionalities.  For 
an  introduction  to  constructing  an  IB  Palette,  please  refer  to  the  NEXTSTEP  on-line 
document  Building  a  Custom  Palette. 

4.1.1  CommandEditor  Class 

The  CommandEditor  class,  a  subclass  of  IBPalette,  is  the  module  responsible  for  inte¬ 
grating  our  Command  Editor  classes  into  IB.  The  instance  data  of  this  class  include  the 
palette  object  types  and  their  iconic  representations  in  the  palette  window.  This  class 
implements  a  single  method,  finishlnstantiate,  which  initializes  all  Command  Editor 
palette  objects  for  IB. 

The  Command  Editor  palette  provides  the  following  classes  to  the  developer:  CECon¬ 
troller,  CEMenuCells,  CESubmenuCell1,  CEMenuConfigCell,  and  TAV  (Figure  2). 
The  subsequent  sections  detail  the  role  and  implementation  of  each  class  relevant  to  its 
operation  in  IB. 

4.1.2  CEController 

The  CEController  is  responsible  for  creating  and  archiving  the  translation  tables  at 
the  completion  of  development  in  IB.  Specifically,  it  traverses  (1)  the  FulIMenu  to 
compose  the  cellTable  and  (2)  the  application’s  object  list  to  compose  the  tavTable. 
Both  tables  are  used  at  runtime  to  reestablish  connection  information  (Section  5.2). 
The  methods  writeCellTable  and  writeTAVTable  build  their  respective  tables  and  ar¬ 
chive  them  to  the  application  NIB.  Both  methods  are  invoked  in  the  CEController’s 
write  method,  which  is  automatically  executed  when  the  developer  selects  “Save”  in 
IB.  The  developer  must  drag  a  single  instance  of  the  CEController  from  our  palette 
into  his  application  NIB. 

4.1.3  CEMenuCell 

The  CEMenuCell  is  subclassed  from  MenuCell  and  adds  several  instance  variables  to 
allov.-  the  targeted  end  user  functionalities.  In  IB,  the  CEMenuCell  associates  its  CE- 
MenuCelllnspector  (Figure  8)  through  the  getlnspectorClassName  method.  The  CE¬ 
MenuCell  also  implements  all  methods  required  of  the  CEMenuCelllnspector  to  set 
instance  data  on  developer  input.  Specifically,  the  CEMenuCell  can  draw  its  visual  in- 


1. CESubmenuCell  is  a  special  case  of  the  CEMenuCell  class  and  is  not  a  distinct  class  in  itself  (Sc  .in  4.1.4) 
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dicator  if  “Default”  is  set  to  false,  update  its  title  when  its  root  state  changes,  store  its 
tool  icon,  set  its  “hasTool”  field,  and  enable/disable  its  CKE  field. 

The  instance  data  of  the  CEMenuCell  class  map  to  particular  functionalities  in  the  fol¬ 
lowing  manner. 

•  States — Each  CEMenuCell  can  have  multiple  states,  and  each  state  repre¬ 
sents  a  different  title  to  be  displayed  once  the  menu  item  is  selected  by  the 
end  user.  States  are  stored  in  a  simple  list,  with  one  state  marked  as  the  root 
state  to  be  displayed  initially.  We  provide  methods  that  allow  the  developer  to 
integrate  his  application  logic  with  this  state  list.  The  application  is  responsi¬ 
ble  for  changing  the  menu  item’s  state.  The  CEMenuCell  automatically  up¬ 
dates  its  title  in  IB  when  the  developer  edits  the  root  state  title.  Conversely, 
the  root  state  title  in  the  CEMenuCelllnspector  updates  should  the  developer 
edit  the  CEMenuCell  directly. 

•  Action — Each  CEMenuCell  performs  a  specific  action  when  selected  by  the 
end  user.  The  mechanism  for  establishing  a  target  connection  is  the  standard 
IB  method  of  Control-dragging  from  the  menu  item  to  the  target  object. 

•  Textual  Description — The  developer  can  provide  a  description  of  the  menu 
item  by  typing  directly  in  the  “Menu  Description”  field  in  the  CEMenuCel¬ 
llnspector.  This  description  is  available  to  the  user  in  the  Menu  Editor. 

•  Icon — The  developer  can  load  an  image  as  the  icon  for  a  particular  CEMenu¬ 
Cell.  This  icon  is  used  to  represent  the  menu  item  in  a  TAV. 

•  Has  Tool — Wh  n  true,  this  boolean  field  indicates  that  the  CEMenuCell  has 
an  icon  and  can  be  dropped  into  a  TAV  at  runtime. 

•  Disabled — CEMenuCells  configured  as  “Disabled”  will  disallow  the  end  us¬ 
er’s  selection  of  that  item  at  runtime.  If  “Disabled”  is  set  to  true  for  an  item, 
the  menu  structure  displays  that  item  in  “grayed  out”  fashion. 

•  Default  Status — CEMenuCells  configured  as  “Default”  are  members  of  the 
BasicMenu  and  are  included  in  the  visible  menu  loaded  at  runtime  in  the  ab¬ 
sence  of  a  user  customization  profile.  The  user  can  delete  CEMenuCells 
from  the  visible  menu;  any  item  the  developer  considers  permanent  to  the  ap¬ 
plication  menu  should  be  integrated  as  a  regular  NEXTSTEP  MenuCell  in¬ 
stance. 

4.1.4  CESubmenuCell 

The  CESubmenuCell  is  actually  implemented  as  a  CEMenuCell  whose  target  is  a 
CEMenu  (Figure  9).  Such  CEMenuCells  answer  true  to  hasSubmenu  and  draw  them¬ 
selves  with  an  additional,  right-adjusted  submenu  arrow.  When  the  developer  drops  a 
CESubmenuCell  onto  the  application  menu  in  IB,  the  structure  being  added  consists 
of  the  top  level  CEMenuCell,  a  CEMenu  that  is  the  target  of  the  toplevel  CEMenu¬ 
Cell,  and  another  CEMenuCell  contained  in  that  CEMenu.  The  CESubmenuCell  as¬ 
sociates  its  inspector,  the  CEMenuCelllnspector,  with  the  getlnspectorClassName 
method.  The  instance  fields  of  meaning  for  a  CESubmenuCell  are  “Default”  and  “Dis¬ 
able.”  The  “Default”  status  includes  the  submenu  in  the  BasicMenu.  The  “Disable” 
status  precludes  user  selection  of  that  CESubmenuCell. 
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FIGURE  9  The  Anatomy  of  a  CESubmenuCell 


Upper  Menu  Curtain 


4.1.5  “Menu  Configuration”  Submenu 

We  implement  the  "Menu  Configuration”  submenu  as  a  stub  object.  The  developer  can 
drag  the  item  from  the  Command  Editor  palette  onto  the  application  menu.  The  entity 
added,  however,  is  simply  an  instance  of  CEMenuConfigCell.  CEMenuConfigCell  is 
a  subclass  of  CEMenuCell  that  adds  no  data  or  methods  (class  or  instance).  In  this 
sense,  the  CEMenuConfigCell  class  is  functionally  equivalent  to  the  CEMenuCell 
class.  The  dropped  cell  is  used  as  an  attach  point  for  the  “Menu  Configuration”  sub¬ 
menu  at  runtime.  In  the  construction  of  the  BasicMenu,  the  CEController  searches 
for  a  cell  of  class  CEMenuConfigCell  and  attaches  the  “Menu  Configuration”  sub- 
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menu  to  this  cell.  The  developer  should  add  only  one  instance  of  CEMenuConfigCell 
to  the  application  menu,  and  he  will  not  be  able  to  view  the  “Menu  Configuration”  sub¬ 
menu  in  IB. 

4.1.6  TAV 

Tool  Acceptor  Views  are  instances  of  the  CEToolView  class.  CEToolView  is  a  sub¬ 
class  of  CEIconView,  which  is  itself  a  subclass  of  View.  The  TAV  class  inherits  the 
ability  to  display  an  image  and  respond  to  input  from  the  View  class.  The  CEIcon¬ 
View  class,  in  turn,  adds  the  ability  to  set  the  image  from  a  file  and  display  the  image 
in  a  “ghosted”  style.  Finally,  the  TAV  contains  DND  logic  and  can  set  its  instance  data 
given  a  CEMenuCell.  Specifically,  the  TAV  displays  the  icon  associated  with  a  CE- 
MenuCell  and,  on  user  selection  at  runtime,  sends  a  message  to  the  CEMenuCell’s 
target  object  with  the  appropriate  selector. 

The  TAV  associates  its  inspector,  the  CETAVInspector,  with  the  getlnspectorCIass- 
Name  method.  The  developer  uses  the  inspector  to  specify  the  border  style  of  the  se¬ 
lected  TAV. 

4.2  Implementation  of  User  Functionalities 

4.2.1  CEController  and  the  Startup  Sequence 

The  CEController  is  responsible  for  all  initialization  and  configuration  of  the  menus 
and  TAVs  on  startup.  Additionally,  the  CEController  processes  many  user  customiza- 
tions  committed  in  the  Menu  Editor. 

On  startup,  the  CEController  executes  the  following  sequence. 

1 .  The  CEController  loads  the  translation  tables  (cellTable  and  tavTable)  containing 
keys  or  unique  identifiers  (UIDs)  for  the  menu  and  TAVs. 

2.  The  CEController  traverses  the  hierarchical  FullMenu,  replacing  instances  of 
Menu  and  Matrix  with  instances  of  CEMenu  and  CEMenuMatrix.  The  replaced 
objects  are  placed  on  a  list  for  deallocation  later. 

3.  The  CEController  traverses  the  FullMenu  once  again,  loading  UIDs  into  the  ap¬ 
propriate  CEMenuCells.  This  pass  also  dictates  that  the  CEController  create  man¬ 
agement  tables  for  each  MenuCell  instance  (Section  5.2). 

4.  The  CEController  then  initializes  the  “Menu  Configuration”  submenu  and  loads 
its  four  UIDs  into  the  cellTable  ("Configure  Menus,”  "Save  Configuration,”  “Load 
Configuration,”  and  “Show/Hide  Configurable  Cells”). 

5.  The  CEController  builds  the  visible  menu.  This  process  takes  one  of  two  paths. 

5a.  If  the  user’s  profile  (.applicationName. ceinfo)  does  not  exist  in  his  home  di¬ 
rectory,  we  construct  and  present  the  BasicMenu.  To  do  this,  the  CEControl¬ 
ler  replicates  the  FullMenu  with  a  recursive  method  called  deepCopy 
(Section  5.6).  The  CEController  then  removes  items  not  marked  “Default” 
from  the  new  copy  of  the  FullMenu  with  filterMenuStructure.  The  copy  is 
installed  as  the  application  menu.  We  do  this  filtration  once  only,  and  the  Ba¬ 
sicMenu  is  archived  to  the  application  NIB  to  avoid  redundant  work  in  subse¬ 
quent  invocations  of  the  application. 
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5b.  If  the  user’s  profile  exists,  the  CEControlIer  reads  the  visible  menu  and  TAV 
configuration  from  this  archive.  As  part  of  this  load  procedure,  each  CEMe- 
nuCell  restores  its  connection  information  using  the  cellTable  in  the  CECon- 
troller.  Similarly,  the  CEControlIer  uses  its  tavTable  to  restore  connection 
information  for  each  TAV. 

6.  The  CEControlIer  attaches  the  “Menu  Configuration”  submenu  to  the  newly  con¬ 
structed  menu.  It  then  makes  this  the  visible  menu  with 

(NXApp  setMainMenu:  visibleMenu] . 

7.  Items  on  the  list  composed  in  Step  2  are  deallocated.  The  necessity  for  this  delayed 
action  is  discussed  in  Section  5.3. 

When  the  user  selects  “Load  Configuration”  from  the  “Menu  Configuration”  submenu 
and  enters  a  valid  file  name  in  the  subsequent  dialog  box,  the  CEControlIer  loads  the 
file,  effectively  executing  step  5b.  The  existing  visible  menu  is  deallocated  and  the 
newly  loaded  menu  is  set  with 

[NXApp  setMainMenu:  newMenu] . 

There  is  no  need  to  attach  the  “Menu  Configuration”  submenu;  the  archived  menu 
structure  already  contains  this  submenu.  Conversely,  the  CEControlIer  archives  the 
menu  structure  and  TAV  configuration  to  disk  when  the  user  selects  “Save  Configura¬ 
tion.” 

The  next  section  describes  the  CEControlIer  responsibilities  necessitated  by  the 
Menu  Editor. 

4.2.2  Menu  Editor 

The  Menu  Editor  is  a  window  that  resides  in  the  CEControlIer  NIB  and  is  brought 
forth  by  the  CEControlIer  when  the  user  selects  “Configure  Menus”  from  the  “Menu 
Configuration”  submenu.  The  Menu  Editor  contains  several  components  that  allow 
the  user  to  browse  the  set  of  available  commands,  specify  CKEs,  and  add  items  to  the 
application  menu. 

The  CEBrowserMatrix,  which  displays  the  set  of  available  commands,  is  a  subclass 
of  BrowserMatrix.  We  add  DND  logic  to  provide  the  capability  to  drag  a  cell  from  the 
browser  onto  a  menu  curtain.  Each  item  displayed  in  the  browser  is  a  CEBrowserCell. 
This  cell  contains  a  reference  to  the  equivalent  cell  in  the  FullMenu  (Figure  10). 
When  the  CEBrowserMatrix  detects  a  drag,  the  selected  CEBrowserCell  is  told  to 
write  itself  to  a  private  pasteboard.  The  CEBrowserCell  instructs  its  FullMenu  equiva¬ 
lent  cell  to  write  its  data  to  this  pasteboard,  including  its  UID.  On  the  subsequent  drop, 
the  receiving  CEMenu  reads  the  cell  information  from  the  pasteboard.  The  UID  is 
then  used  to  access  the  original  FullMenu  member.  This  member  contains  a  valid  con¬ 
nection  to  its  target.  This  connection  information  is  replicated  for  the  newly  read  cell 
(Section  5.2).  The  same  logic  allows  the  user  to  drag  a  CEMenuCell  onto  a  TAV. 

The  “Additional  Submenu”  portion  of  the  Menu  Editor  contains  an  instance  of  the 
CEAdditionalSubmenuView  class.  This  subclass  of  Button  implements  additional 
methods  for  DND.  It  also  allows  the  specification  of  its  title,  and  the  user  can  do  so  by 
typing  in  the  text  field  in  the  “Additional  Submenu”  portion  of  the  Menu  Editor.  The 
CEAdditionalSubmenuView  draws  itself  with  the  submenu  arrow  and  contains  refer¬ 
ences  to  its  target  CEMenu  curtain  and  a  single  CEMenuCell  item  in  that  curtain 
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When  dragged,  the  CEAdditionalSubmenuView  writes  itself  to  the  Pasteboard,  in¬ 
cluding  its  referenced  instances  of  CEMenu  and  CEMenuCell.  On  the  subsequent 
drop,  the  receiving  CEMenuMatrix  curtain  reads  the  entire  structure  from  the  Paste¬ 
board  and  integrates  the  new  submenu  containing  a  single  item  into  the  menu  structure. 


The  customization  of  CKEs  requires  intervention  by  the  CEControlIer  (Figure  11). 
When  the  user  enters  a  letter  in  the  “Command  Equivalent  Key”  field  of  the  Menu  Edi¬ 
tor,  the  CEControlIer  follows  a  reference  contained  in  the  selected  CEBrowserCell. 


This  reference  points  to  a  member  of  the  FullMenu — a  CEMenuCell.  The  CECon- 
troller  then  uses  the  UID  of  this  CEMenuCell  to  collect  members  of  the  visible  menu 


that  are  equivalent  to  this  CEMenuCell.  The  CEControlIer  configures  these  instances 
to  activate  on  the  new  CKE.  If  no  such  instances  are  found,  the  CEControlIer  ignores 
the  new  CKE.  The  entry  in  the  FullMenu  is  not  modified;  the  next  selection  of  the 
same  command  will  reflect  the  CKE  originally  set  by  the  developer.  The  customization 
of  the  “Enable/Disable  CKE”  field  is  analogous. 


FIGURE  10 


The  Association  Between  CEBrowserCells  and  CEMenuCells 

CEFullMenu 
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FIGURE  11  References  for  CKE  Updates 


CEFuliMenu 


4.2.3  DND  in  Menus 

The  provision  of  DND  logic  in  the  application  menu  entails  replacement  of  instances 
of  Menu  and  Matrix  with  instances  of  CEMenu  and  CEMenuMatrix.  On  a  Control- 
drag,  the  CEMenuMatrix  will  detect  the  drag  and  map  the  mouse  coordinates  to  one 
of  its  members — a  CEMenuCell.  This  cell  implements  read  and  write  methods  that 
allow  it  to  initialize  itself  from  the  pasteboard  and  format  itself  to  the  pasteboard,  re¬ 
spectively.  The  read  restores  the  CEMenuCell’s  target  action  using  the  cellTable. 

The  CEMenu,  then,  is  used  to  manage  instances  of  MenuCell.  The  MenuCell  class 
cannot  read  or  write  without  losing  its  connection  information  (Section  5.2).  The  CE¬ 
Menu  maintains  a  table  of  [UID,  MenuCell  reference]  pairs  that  facilitates  the  restora¬ 
tion  of  each  MenuCell’s  target  action. 
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4.2.4  DNDinTAVs 

We  implement  TAVs  as  a  subclass  of  View.  On  a  simple  mouseDown,  a  TAV  sends  its 
target  object  the  appropriate  selector.  A  TAV  stores  its  target  and  selector  information 
in  a  CEMenuCell  instance  datum.  On  a  Control-drag,  a  TAV  writes  its  CEMenuCell 
to  the  Pasteboard  and  invalidates  its  CEMenuCell  instance  datum.  The  visual  indica¬ 
tor  is  the  “ghosted”  icon  on  the  TAV  itself.  On  a  drop,  the  receiving  TAV  reads  the  CE¬ 
MenuCell  from  the  Pasteboard  and  assigns  its  CEMenuCell  reference  to  this  newly 
allocated  cell. 


5.0  Challenges  and  Resolution 


The  challenges  we  faced  in  completing  the  Command  Editor  stem  from  two  aspects  of 
the  NEXTSTEP  environment.  The  first  aspect  is  the  process  by  which  NEXTSTEP  ar¬ 
chives  an  application  package  (executable  and  NIBs)  and  the  subsequent  unarchival 
(reconstitution)  of  the  application’s  objects  at  runtime.  The  second  aspect  is  NEXT’S 
private  API  that  hides  some  functionalities  of  IB  from  the  developer. 

5.1  MenuTemplate 

The  NEXTSTEP  implementation  of  menus  is  hidden  from  the  developer  in  IB.  IB  de¬ 
ploys  a  “MenuTemplate”  hidden  in  an  API  private  to  NEXT  to  implement  the  menu 
structure.  Consequently,  our  original  design  could  not  be  implemented.  The  reader 
may  recall  that  DND  was  to  be  achieved  by  replacing  the  Matrix  instances  of  the  menu 
with  instances  of  our  CEMenuMatrlx  in  IB.  While  we  indeed  perform  this  replace¬ 
ment,  this  action  is  done  to  the  FullMenu  on  startup.  As  a  result,  we  now  construct  the 
visible  menu  from  the  FullMenu,  filtering  out  non-“Default”  members  of  the  hierar¬ 
chy. 

5.2  Restoring  Connection  Information 

The  standard  NEXTSTEP  API  provides  the  write  method  for  the  archival  of  objects. 
This  write  method  formats  data  to  a  stream  and  can  be  used  to  archive  an  object  to 
disk.  Data  written  include  instance  variables  and  methods.  If  the  object  contains  refer¬ 
ences  to  other  objects,  however,  these  references  are  not  written  and  read  correctly  un¬ 
less  the  referenced  objects  are  likewise  written  to  the  same  stream.  The  write  method 
actually  writes  out  a  preset  value  for  all  references  to  external  objects.  The  read  sets 
the  reference  to  NULL  when  it  encounters  the  preset  value,  effectively  destroying  the 
connection  information. 

In  a  typical  application  developed  in  IB,  connection  information  is  archived  in  the  NIB 
that  encapsulate  the  objects  involved  in  that  connection.  This  archival  method  is  pri¬ 
vate  to  NEXT  and  presumably  does  much  more  than  the  write  method.  At  runtime, 
NEXTSTEP  unarchives  the  NIBs  and  establishes  the  connection  information  correctly. 

Our  challenge  stems  from  the  need  to  retain  the  connection  information  in  an  object  de¬ 
spite  using  the  write  method.  Specifically,  we  require  the  write  mechanism  to  enable 
DND;  an  object  with  external  references  (a  CEMenuCell  with  a  target  object)  is  writ¬ 
ten  to  (and  read  from)  a  private  pasteboard  for  each  DND  session.  The  same  mecha- 
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nism  saves  the  end  user’s  customizations  of  the  application  menu  when  the  customized 
menu  recursively  writes  itself  to  disk. 

Each  CEMenuCell  has  a  target  object  to  which  it  will  send  a  selector  when  activated 
by  the  end  user.  The  developer  specifies  this  connection  in  IB  by  Control-dragging  an 
IB  wire  from  the  CEMenuCell  to  its  target  object.  At  the  completion  of  development 
in  IB,  the  FulIMenu  structure  archives  to  the  application  NIB.  The  structure  of  this 
FullMenu  is  fixed  by  the  developer  and  remains  constant  throughout  invocations  of 
the  application.  At  runtime,  NEXTSTEP  reconstitutes  the  FullMenu  with  valid  con¬ 
nections  and  targets.  Hence,  all  the  CEMenuCells,  their  target  objects,  and  connection 
information  exist  and  are  valid  at  runtime. 

If  we  ask  a  CEMenuCell  to  write  itself,  we  essentially  lose  the  reference  to  its  target 
object.  To  facilitate  DND  and  profiling  of  the  end  user’s  customization,  we  implement 
a  translation  table  that  pairs  each  CEMenuCell  in  the  FullMenu  with  a  unique  key 
(UID).  At  the  completion  of  development  in  IB,  the  CEController  traverses  the  appli¬ 
cation’s  object  list  and  inserts  [UID,  CEMenuCell  reference]  pairs  for  every  CEMe¬ 
nuCell  instance  into  a  translation  table.  The  CEController  then  archives  this  table  in 
the  application  NIB.  At  runtime,  the  table  is  instantiated  and  its  object  references  point 
to  items  in  the  instantiated  FullMenu.  Each  CEMenuCell  instance  in  the  FullMenu 
uses  the  table  to  assign  its  UID  to  an  internal  variable  for  future  use. 

When  a  drag  occurs  at  runtime,  the  dragged  CEMenuCell  writes  itself  to  the  drag 
pasteboard.  On  the  drop,  the  CEMenuCell  is  read  from  this  pasteboard,  complete  with 
a  UID.  The  CEController  uses  the  UID  to  look  up  the  object  reference  in  the  transla¬ 
tion  table.  This  object  reference  yields  the  original  CEMenuCell  in  the  FullMenu. 
Given  this  original  CEMenuCell,  which  contains  the  valid  reference  to  its  target  ob¬ 
ject,  the  target  connection  can  be  restored. 

Similarly,  when  the  end  user  saves  his  profile,  the  customized  menu  recursively  writes 
itself  to  disk.  The  unique  key  is  written  for  each  CEMenuCell.  On  a  subsequent  run  of 
the  application,  the  CEController  loads  this  archive.  Since  this  a  complete  archive  of 
an  object,  the  target  actions  do  not  need  restoration. 

We  treat  TAVs  in  a  similar  manner.  At  the  completion  of  development  in  IB,  the  CE¬ 
Controller  obtains  the  list  of  all  objects  and  traverses  it  looking  for  objects  of  class 
TAV.  The  CEController  composes  a  second  table  to  store  [tavUID,  CEMenuCell 
copy]  tuples. 

Instances  of  MenuCell  further  complicate  the  connection  restoration.  Recall  that  one 
of  our  original  design  objectives  was  to  retain  the  full  functionality  of  NEXTSTEP,  par¬ 
ticularly  IB.  We  allow  the  developer  to  use  the  default  IB  MenuCell  to  compose  the  ap¬ 
plication  menu.  The  end  user  can  drag  a  submenu  from  the  Menu  Editor  (onto  the 
application  menu)  that  contains  MenuCell  instances.  The  connection  for  the  MenuCell 
is  lost  when  the  submenu  recursively  writes  itself  to  the  pasteboard.  A  key  is  used  in 
this  case  to  restore  the  connection,  much  like  for  CEMenuCells.  The  difficulty  is  now 
associating  the  key  with  the  MenuCell  to  be  written.  The  MenuCell  is  a  NEXTSTEP 
“appkit”  class.  The  UID,  then,  is  stored  in  the  CEMenu  which  contains  that  Menu- 
Cell.  Each  CEMenu  in  the  application  menu  structure  must  manage  a  set  of  Menu- 
Cells  (and  SubmenuCells).  For  each  MenuCell,  the  CEMenu  will  maintain  the  unique 
key  that  refers  to  the  original  MenuCell  in  the  FullMenu. 
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Submenus  are  a  special  case  for  archival  and  restoration.  When  a  submenu  item  writes 
itself,  the  entire  recursive  structure  is  written  to  the  stream.  This  includes  the  submenu 
curtain  as  well  as  the  menu  items  that  curtain  contains.  Though  the  targets  of  the  menu 
items  are  lost  via  the  standard  write,  the  target  of  the  submenu  item  is  the  submenu 
curtain,  which  is  written  to  the  archive  along  with  the  upper  level  submenu  item.  No 
unique  key  is  needed  to  reestablish  the  connection.  When  a  submenu  item  is  read,  the 
target  object  is  set  to  the  submenu  curtain  (CEMenu)  automatically.  As  curtain  items 
are  read  back,  we  use  unique  keys  to  restore  their  individual  connections. 

5.3  Race  Conditions 

A  peculiar  race  condition  occurs  in  the  process  by  which  NEXTSTEP  instantiates  an 
application’s  NIB  at  runtime.  Typically,  an  object  receives  an  awakeFromNib  mes¬ 
sage  once  it  is  instantiated  by  NEXTSTEP.  This  message  signifies  that  all  objects  in 
that  NIB  are  instantiated  and  valid.  The  developer  can  implement  this  method  to  per¬ 
form  any  initialization  or  synchronization  desired.  In  a  NIB  that  consists  of  many  ob¬ 
jects,  the  order  in  which  objects  receive  the  awakeFromNib  message  is  not  known. 
Therefore,  any  dependency  in  an  object’s  awakeFromNib  method  on  another  object 
having  received  the  awakeFromNib  message  is  prone  to  error. 

This  aspect  of  the  instantiation  process  gives  rise  to  a  race  condition  that  the  CECon- 
troller  must  address.  When  the  CEControlIer  receives  its  awakeFromNib,  it  pro¬ 
ceeds  to  replace  recursively  the  FullMenu’s  Menu  and  Matrix  instances  with 
instances  of  CEMenu  and  CEMenuMatrix.  Replacement  entails  freeing  the  replaced 
Menu  and  Matrix  instances.  While  the  Menu  and  Matrix  instances  certainly  exist, 
many  of  them  have  yet  to  receive  their  awakeFromNib  message.  If  we  free  these  in¬ 
stances  before  the  awakeFromNib,  the  unarchival  process  will  eventually  send  mes¬ 
sages  to  non-existent  objects,  causing  the  application  to  crash. 

The  work  around  for  this  race  condition  entails  placement  of  the  objects  to  be  freed  on 
a  list  and,  finally,  freeing  of  this  list  once  the  awakeFromNib  is  sent  to  each  object. 
We  accomplish  the  delayed  freeing  of  objects  by  placing  the  action  on  the  applica¬ 
tion’s  event  queue,  with  the  guarantee  that  this  event  queue  entry  will  be  processed 
only  after  the  current  event  is  finished.  The  current  event  is  the  unarchival  of  the  NIB. 
Hence,  we  free  the  replaced  Menu  and  Matrix  instances  only  after  the  unarchival  pro¬ 
cess  is  completely  finished. 

5.4  Submenu  Addition 

The  addition  of  submenus  to  the  application  menu  by  the  end  user  at  runtime  dictates 
that  we  implement  a  method  by  which  a  DND  submenu  structure  is  added  to  a  menu 
curtain.  Recall  that  the  end  user  can  add  submenus  in  one  of  two  ways:  by  dragging 
the  “Additional  Submenu”  item  from  the  Menu  Editor  onto  the  application  menu  or 
by  dragging  a  menu  item  that  represents  a  submenu  from  the  CEBrowserMatrix  in 
the  Menu  Editor. 

When  the  “Additional  Submenu”  item  is  dragged  from  the  Menu  Editor,  a  submenu 
structure  consisting  of  one  item  is  written  to  the  drag  pasteboard.  The  structure  written 
includes  the  upper  item,  its  submenu  curtain,  and  the  singular  lower  member  item.  The 
submenu  curtain  is  the  target  object  of  the  upper  menu  item.  On  the  subsequent  drop, 
the  drop-curtain’s  CEMenuMatrix  allocates  a  new  CEMenuCell  which  reads  itself 
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from  the  drag  pasteboard.  This  read  process  restores  the  connection  information;  the 
submenu  curtain  is  once  again  the  target  object  of  the  upper  menu  item.  The  CEMenu- 
Matrix  integrates  the  new  submenu  item  into  its  list  of  items. 

When  a  menu  item  representing  a  submenu  is  dragged  from  the  browser  area  of  the 
Menu  Editor,  the  process  by  which  the  new  submenu  gets  incorporated  into  the  exist¬ 
ing  menu  is  identical  to  that  of  the  previous  case.  In  this  scenario,  however,  the  items 
in  the  submenu  curtains  have  connections  that  must  be  restored.  Each  CEMenuCell 
can  restore  its  own  connection  information  with  data  written  on  the  write  with  its  read 
method.  Hence,  the  process  by  which  the  new  submenu  item  is  created  and  initialized 
from  the  pasteboard  also  restores  the  member  items’  connections. 

5.5  Populating  the  Matrix 

Populating  a  matrix  poses  a  special  problem  for  our  development  effort.  To  add  a  cell 
to  a  Matrix,  The  NEXTSTEP  interface  to  its  “appkit”  Matrix  class  dictates  that  we  first 
ask  the  Matrix  to  create  a  new  cell.  Second,  we  assign  instance  variables  of  that  cell  ex¬ 
plicitly.  The  problems  with  this  mechanism  are  (1)  the  cell  is  always  added  at  the  end 
of  the  list  (bottom  of  menu  curtain)  and  (2)  we  must  copy  a  record  structure  to  assign 
cell  instance  data.  We  need  the  capability  to  insert  a  pre-allocated  cell  into  the  Matrix 
at  any  position. 

To  this  end,  we  have  implemented  a  method  which  inserts  a  cell  in  the  Matrix  without 
copying  the  structural  data  explicitly.  The  method  accomplishes  this  by  pointer  manip¬ 
ulation.  First,  the  Matrix  is  asked  to  allocate  a  new  cell.  We  then  obtain  the  pointer  to 
this  cell,  reset  the  pointer  to  our  cell,  and  free  the  newly  allocated  cell.  We  have  just 
avoided  the  explicit  copy,  but  our  cell  is  not  at  the  desired  location.  Next,  we  traverse 
the  Matrix’s  list  of  pointers  and  insert  our  cell  in  the  correct  location  by  shifting  the  ap¬ 
propriate  pointers. 


5.6  Deep  Copy 

The  duplication  of  an  existing  recursive  data  structure  requires  the  recreation  of  each 
member  node.  While  an  object  that  contains  references  to  additional  objects  can  cer¬ 
tainly  duplicate  itself  via  the  copy  method,  the  new  copy  contains  references  to  the 
same  instances  pointed  to  by  the  original  object,  as  the  following  NEXTSTEP  on-line 
documentation  clearly  shows. 

copy 

-copy 

Returns  a  new  instance  that’s  an  exact  copy  of  the  receiver.  This 
method  creates  only  one  new  object.  If  the  receiver  has  instance  vari¬ 
ables  that  point  to  other  objects,  the  instance  variables  in  the  copy 
will  point  to  the  same  objects.  The  values  of  the  instance  variables 
are  copied,  but  the  objects  they  point  to  are  not. 

Our  duplication  of  a  subset  of  the  FullMenu  to  provide  the  application  menu  at  run¬ 
time  dictates  that  we  duplicate  each  member  menu  cell.  If  we  were  to  employ  the  stan¬ 
dard  copy  mechanism,  the  new  menu  will  contain  references  to  the  original  menu  cells 
in  the  FullMenu.  When  the  end  user  customizes  the  menu,  modifications  made  to  the 
newly  created  menu  will  alter  the  configuration  of  the  FullMenu.The  original  hierar- 


A  Command  Editor  Tool  for  NEXTSTEP 


21  of  27 


marble 

••••• 


Final  Report  for  Contract  #  DAAH01-93-C-R013 


chy  and  instance  data  provided  by  the  developer  will  be  lost.  We  cannot  allow  this  to 
happen.  This  is  the  motivation  for  the  deepCopy  method,  which  recursively  recreates 
each  node  in  a  given  menu  structure  and  replicates  all  referenced  objects. 


6.0  Compromises  to  Functionalities 


6.1  States  with  Individual  Targets 

Our  original  design  allowed  each  state  of  a  CEMenuCell  to  have  a  distinct  target  ac¬ 
tion.  We  assumed  that  a  mechanism  exists  in  IB  that  would  allow  the  developer  to  es¬ 
tablish  the  connection  from  the  individual  state  to  its  target  object.  This  is  typically 
done  through  the  Control-drag  mechanism  that  displays  an  IB  wire.  Unfortunately,  the 
IB  connection  establishment  mechanism  is  private  to  IB.  All  states  will  represent  the 
same  action. 

6.2  System  Menus 

The  “Windows”  and  “Services”  menus  are  maintained  by  the  system.  As  such,  their 
items  are  determined  dynamically  over  the  course  of  the  system’s  execution.  We  can¬ 
not  add  DND  to  these  system  menus;  doing  so  will  potentially  cause  a  plethora  of  er¬ 
rors  that  affect  components  external  to  the  application. 


A  Command  Editor  Tool  for  NEXTSTEP 


22  of  27 


marble 

••••• 

Final  Report  for  Contract  #  DAAH01-93-C-R013 

Appendix  A 

Class  Descriptions 

This  section  lists  the  classes  of  the  Command  Editor:  those  used  by  the  developer  as 
and  those  necessary  to  construct  the  Command  Editor  itself.  Each  entry  contains  the 
class  and  category  name,  its  superclass  if  applicable,  the  file  that  contains  the  imple¬ 
mentation,  and  a  brief  description  of  its  purpose  and  use. 

className(category):  superclass  in  fileName 

description 

Fields  that  are  inapplicable  for  an  entry  are  denoted  with  a  Categories  group  meth¬ 
ods  by  common  purpose  and  separate  logically  distinct  sets  of  methods.  A  category  en¬ 
try  begins  with  the  class  name  followed  by  the  parenthesized  category  name.  The 
entries  appear  in  alphabetical  order. 

ApplicationfCEAdd/r/ons):  -  in  Applications_CEAdditions.[mh] 

This  category  adds  one  method  to  the  standard  Application  class.  The  CEController 
uses  this  method,  setWindowsList,  to  obtain  the  list  of  windows  in  the  application  and 
access  the  application  menu  at  runtime. 

CEAdditionalSubmenuView:  Button  in  CEAdditionalSubmenuView.[mh] 

This  class  implements  the  draggable  submenu  button  in  the  Menu  Editor's  “Addition¬ 
al  Submenu”  portion.  The  end-user  can  set  the  title  of  this  submenu  and  drag  the  but¬ 
ton  into  the  menu  structure.  On  the  drop,  the  new  submenu  contains  a  single 
configurable  item. 

CEBrowserCell:  NXBrowserCell  in  CEBrowserCell.[mh] 

CEBrowserCells  are  used  in  the  Menu  Editor  to  allow  the  user  to  browse  the  set  of 
available  commands.  Each  CEBrowserCell  contains  a  proxy  or  reference  to  its  repre¬ 
sentative  in  the  FullMenu  and  displays  the  title  of  its  proxy’s  root  state. 

CEBrowserMatrix:  CEDragMatrix  in  CEB  row  serMatri  r. .  [mh  ] 

The  CEBrowserMatrix  inherits  DND  logic,  allowing  the  end-user  to  drag  a  CE¬ 
BrowserCell  from  the  Menu  Editor  into  the  application  menu.  Most  of  the  implemen¬ 
tation  of  the  DND  capability  is  in  the  abstract  superclass  CEDragMatrix.  The 
CEBrowserMatrix  supplies  the  verification  methods  to  tailor  the  drag  sessions.  Spe¬ 
cifically,  the  end-user  must  hold  down  the  Control  key  to  start  a  drag.  In  addition,  the 
CEBrowserMatrix  does  not  accept  drops. 

CEController:  Object  in  CEControlIer.[mh] 

This  section  of  the  CEController  contains  the  methods  necessary  to  execute  the  se¬ 
quence  detailed  in  Section  4.2.1.  These  methods  handle  the  archival  and  unarchival  of 
the  three  menus  (FullMenu,  BasicMenu,  and  CustomizedMenu)  and  build,  maintain, 
and  manipulate  the  UID  translation  tables  (cellTable  and  tavTable). 

CEControIler(7Z?):  -  in  CEControlIerJB.m 

This  category  of  CEController  contains  methods  to  write  the  UID  tables  (cellTable 
and  tavTable)  to  the  application  NIB  at  the  completion  of  development  in  IB. 

CEControIl er(UserDefaults):  -  in  CEControlIer_UserDefau!ts.m 
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This  category  of  CEController  c'-uains  methods  to  load  and  save  the  end-user's  con¬ 
figurations.  The  CEController  loads  the  CustomizedMenu  and  configures  the  TAVs 
using  methods  in  this  category. 

CEControllerf  Userlnteraction):  -  in  CEController_UserInteractions.m 

Methods  in  this  category  implement  the  selections  in  the  “Menu  Configuration”  sub¬ 
menu.  The  CEController  uses  methods  in  this  category  to  bring  forth  the  Menu  Edi¬ 
tor  and  show  or  hide  configurable  cells.  This  category  additionally  handles  all  end- 
user  customizations  done  through  the  Menu  Editor:  specification  and  enabling  of 
CKEs,  traversal  of  the  FullMe.iu  through  the  browser,  selection  and  dragging  of  CE- 
BrowserCells,  and  addition  of  a  submenu. 

CEDragMatrixView.  Matrix  in  CEDragMatrixView.fmh] 

This  is  the  abstract  superclass  for  CEBrowserMatrix  and  CEMenuMatrix,  both  of 
which  require  different  DND  capabilities.  This  class  implements  the  DND  methods 
and  leaves  stub  methods  that  a  subclass  must  override  to  tailor  the  DND  capabilities. 
To  facilitate  *he  drag,  the  CEDragMatrixView  accepts  the  mouseDown  event,  maps 
the  mouse  coordinates  to  the  draggable  item,  obtains  the  drag  image,  obtains  the  drag 
data,  and  writes  that  drag  data  to  a  private  pasteboard.  To  facilitate  the  drop,  the  CE¬ 
DragMatrixView  updates  the  cursor  on  draggingEntered  and  draggingUpdated  and 
reads  data  from  the  private  pasteboard  on  the  actual  drop. 

CEIconView:  View  in  CEIconView.[mh] 

This  is  the  abstract  superclass  of  CEToolView  (which  implements  TAVs).  CEIcon¬ 
View  contains  methods  to  display  an  image  centered  in  a  view  with  options  for  back¬ 
ground  style  and  ghosting. 

CEMenu:  Menu  in  CEMenn.[mh] 

The  CEMenu  manages  its  MenuCells  and  their  targets  to  allow  the  restoration  of  con¬ 
nection  information.  In  addition,  the  CEMenu,  at  the  request  of  the  CEController, 
does  the  actual  replacement  of  Matrix  with  CEMenuMatrix  for  itself  and  its  sub¬ 
menus.  The  CEMenu  also  implements  methods  to  add  and  remove  submenus,  update 
CKEs,  and  update  enable/d  sable  display  status  of  its  items. 

CEMenuCell:  MenuCell  in  CEMenuCell.[mh] 

An  instance  of  CEMenuCell  is  the  atomic  datum  that  represents  t  command  in  the 
menu  structures.  The  CEMenuCell  inherits  basic  menu  item  functionality  from  Menu- 
Cell.  Additional  instance  data  record  its  list  of  states,  icon,  description,  “hasTool”  sta¬ 
tus,  “Default”  status,  CKE,  and  UID.  CEMenuCell  also  contains  methods  to  access, 
manipulate,  and  update  its  instance  data.  The  CEMenuCell  can  display  itself  with  the 
square  notch  to  indicate  either  default  (IB)  or  configurable  (runtime). 

CEMenuCell(/£):  -  in  CEMenuCelUB.m 

This  category  contains  a  single  method  getlnspectcrClassName  that  associates  the 
CEMenuCelllnspector  with  the  CEMenuCell  class.  This  allows  the  developer  to  con¬ 
figure  the  instance  data  of  a  CEMenuCell  in  IB. 

CEMenuConfigCell:  CEMenuCell  in  CEMenuConfigCell.[mh] 

This  is  a  stub  class  used  for  the  attachment  of  the  “Menu  Configuration”  submenu 
(Section  4.1.5). 


A  Command  Editor  Tool  for  NEXTSTEP 


24  of  27 


* 

marble 

••••• 


Final  Report  for  Contract  *  DAAH01-93-C-R013 


CEMenuMatrix:  CEDragMatrix  in  CEMenuMatrix.[mh] 

This  class  allows  the  end-user  to  drag  items  from  and  drop  items  onto  the  application 
menu.  CEMenuMatrix  overrides  its  superclass  method  validateBeginDrag  to  allow 
the  end-user  to  drag  CEMenuCells  from  the  application  menu.  Similarly,  it  overrides 
its  superclass  method  validate:andPerformDrop  to  allow  the  end-user  to  drop  CEMe¬ 
nuCells  into  the  application  menu. 

CEState:  ButionCell  in  CEState.[mh] 

An  instance  of  CEState  maintains  a  title,  a  numeric  identification  tag,  and  a  boolean 
field  that  reflects  whether  or  not  this  instance  is  the  root  state.  Such  instances  are 
grouped  into  a  list  and  stored  in  an  instance  datum  of  the  CEMenuCell  class.  The  de¬ 
veloper  can  access  a  CEState  by  its  numeric  identification  tag  (index)  and  update  the 
menu  item’s  displayed  title  with  the  CEState’s  title. 

CEToolView:  IconView  in  CEToolView.fmh] 

An  instance  of  CEToolView  contains  an  instance  of  CEMenuCell  that  s'  es  the  CE- 
ToolView’s  configuration.  When  the  user  selects  the  CEToolView  instance  (TAV),  the 
TAV  accesses  its  instance  of  CEMenuCell  to  obtain  the  target  object  and  the  selector 
to  send  to  that  target  object.  This  action  effectively  executes  the  configured  command. 
In  addition,  CEToolView  contains  methods  to  implement  the  DND  configuration  capa¬ 
bilities. 

CEToolView(/B):  -  in  CEToolView_lB.m 

This  category  contains  a  single  method  getlnspectorClassName  that  associates  the 
CEToolViewInspector  with  the  CEToolView  class.  This  allows  the  developer  to  spe¬ 
cify  the  border  style  of  a  CEToolView  in  IB. 

Cell (CEAdditions):  -  in  Cell_CEAdditions.[mh] 

This  category  adds  methods  to  the  standard  NEXTSTEP  class  Cell  to  obtain  and  set  a 
single  character  value.  These  methods  facilitate  the  specification  and  updating  of 
CKEs. 

Matrix(CEAdditions):  -  in  Matrix_CL  »dditions.[mh] 

Methods  in  this  category  implement  the  work  around  described  in  Section  5.5. 

NXImag e( CEAdditions):  -  in  NXImage_CEAdditions.[mh] 

This  category  adds  the  method  inilFromRect  to  allow  the  initialization  of  a  NXImage 
from  a  region  of  a  view.  We  use  this  capability  to  piovide  the  dragging  image  when  a 
CEBrowserCell  is  dragged. 

Objectf CEAdditions):  -  in  Object_CEAdditions.[mh] 

This  category  contains  a  single  method  deepCopy  to  replicate  an  object  as  well  as  the 
objects  it  references  (Section  5.6). 
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Appendix  B 

Related  Documents 

A  Command  Editor  Tool  for  NEXTSTEP  and  X-Windows  Systems  (SBIR  Phase  1  Pro¬ 
posal)  for  DARPA/OASB/SBIR,  Submitted  on  July  1,  1992. 

A  Command  Editor  Tool  for  NEXTSTEP  and  X,  Quarterly  Status  Report  under  Con¬ 
tract  #  DAAH01-93-C-R013,  Submitted  on  April  26,  1993. 

A  Command  Editor  Tool  for  X  and  Motif,  Design  Document  under  Contract  # 
DA  AHO 1  -93-C-RO 1 3,  July  1,  1993. 

The  Command  Editor:  A  Manual  for  Users  and  Developers,  under  Contract  # 
DAAHO 1-93-C-RO 1 3,  July  1,  1993. 

End-user  Customizable  Menus  in  the  X  Windowing  Environment  (SBIR  Phase  II  Pro¬ 
posal)  for  Contract  #  DAAHO  1-93-C-RO  13,  July  1, 1993. 
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Appendix  C 

Sources 

Building  a  Custom  Palette 

/NextLibrary/Documentalion/NextDev/Dev- 
Tools/1 8_CustomPalette 

Interface  Builder 

/NextDeveloper/Demos/HeaderViewer.app 

IB  (protocol) 

/NextLibrary/Documentation/GeneraiRef/ 

08_InterfaceBuiIdei7ProtocolsflB.rtf 

IBConnectors 

/NextLibrary/Documentation/GeneralRef/ 

08_InterfaceBuilder/ProtocoIs/TBConnec- 

tors.rtf 

IBDocuments 

/NextLibrary/Documentation/GeneralRefy 

08_InterfaceBuilder/Protocols/IBDocum- 

nets.rtf 

lBDocumentControllers 

/NextLibrary/Documentation/GeneraiRefy 

08_InterfaceBuilder/Protocols/IBDocu- 

ments.rtf 

IBEditors 

/NextLibrary/Documentation/GeneralRef/ 

08_InterfaceBuilder/Protocols/IBEditors.rtf 

IBInspectors 

/NextLibrary/Documentation/GeneralRefy 
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